package com.kexio.file.service;

import java.time.LocalDateTime;
import java.util.List;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.kexio.file.entity.ShareLink;
import com.kexio.file.vo.ShareLinkVO;

/**
 * 文件分享链接服务接口
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface ShareLinkService extends IService<ShareLink> {

    /**
     * 创建分享链接
     *
     * @param fileId 文件ID
     * @param shareType 分享类型（1-公开，2-密码，3-私有）
     * @param password 分享密码（可选）
     * @param validUntil 有效期（可选）
     * @param maxAccessCount 最大访问次数（可选）
     * @param maxDownloadCount 最大下载次数（可选）
     * @param description 分享描述
     * @return 分享链接信息
     */
    ShareLinkVO createShareLink(String fileId, Integer shareType, String password,
                                LocalDateTime validUntil, Integer maxAccessCount, 
                                Integer maxDownloadCount, String description);

    /**
     * 根据分享码获取分享信息
     *
     * @param shareCode 分享码
     * @return 分享链接信息
     */
    ShareLinkVO getByShareCode(String shareCode);

    /**
     * 验证分享链接访问权限
     *
     * @param shareCode 分享码
     * @param password 密码（如果需要）
     * @param clientIp 客户端IP
     * @return 验证结果
     */
    ShareLinkVO validateShareAccess(String shareCode, String password, String clientIp);

    /**
     * 记录分享链接访问
     *
     * @param shareCode 分享码
     * @param clientIp 客户端IP
     * @return 是否成功
     */
    boolean recordAccess(String shareCode, String clientIp);

    /**
     * 记录分享链接下载
     *
     * @param shareCode 分享码
     * @param clientIp 客户端IP
     * @return 是否成功
     */
    boolean recordDownload(String shareCode, String clientIp);

    /**
     * 获取文件的所有分享链接
     *
     * @param fileId 文件ID
     * @return 分享链接列表
     */
    List<ShareLinkVO> getShareLinksByFileId(String fileId);

    /**
     * 获取文件的有效分享链接
     *
     * @param fileId 文件ID
     * @return 有效分享链接列表
     */
    List<ShareLinkVO> getValidShareLinks(String fileId);

    /**
     * 获取用户创建的分享链接
     *
     * @param creatorId 创建者ID
     * @param page 分页参数
     * @return 分享链接分页列表
     */
    Page<ShareLinkVO> getUserShareLinks(String creatorId, Page<ShareLink> page);

    /**
     * 更新分享链接
     *
     * @param shareId 分享ID
     * @param shareType 分享类型
     * @param password 分享密码
     * @param validUntil 有效期
     * @param maxAccessCount 最大访问次数
     * @param maxDownloadCount 最大下载次数
     * @param description 分享描述
     * @return 是否成功
     */
    boolean updateShareLink(String shareId, Integer shareType, String password,
                            LocalDateTime validUntil, Integer maxAccessCount, 
                            Integer maxDownloadCount, String description);

    /**
     * 禁用分享链接
     *
     * @param shareId 分享ID
     * @return 是否成功
     */
    boolean disableShareLink(String shareId);

    /**
     * 启用分享链接
     *
     * @param shareId 分享ID
     * @return 是否成功
     */
    boolean enableShareLink(String shareId);

    /**
     * 删除分享链接
     *
     * @param shareId 分享ID
     * @return 是否成功
     */
    boolean deleteShareLink(String shareId);

    /**
     * 删除文件的所有分享链接
     *
     * @param fileId 文件ID
     * @return 是否成功
     */
    boolean deleteAllShareLinks(String fileId);

    /**
     * 批量处理过期的分享链接
     *
     * @return 处理数量
     */
    int processExpiredLinks();

    /**
     * 批量处理访问次数已达上限的分享链接
     *
     * @return 处理数量
     */
    int processAccessLimitReachedLinks();

    /**
     * 生成分享码
     *
     * @return 分享码
     */
    String generateShareCode();

    /**
     * 生成分享URL
     *
     * @param shareCode 分享码
     * @return 分享URL
     */
    String generateShareUrl(String shareCode);

    /**
     * 获取分享统计信息
     *
     * @param shareId 分享ID
     * @return 统计信息
     */
    java.util.Map<String, Object> getShareStats(String shareId);

    /**
     * 获取用户分享统计
     *
     * @param creatorId 创建者ID
     * @param days 统计天数
     * @return 统计信息
     */
    java.util.Map<String, Object> getUserShareStats(String creatorId, Integer days);

    /**
     * 获取热门分享链接
     *
     * @param limit 限制数量
     * @param days 统计天数
     * @return 热门分享链接列表
     */
    List<ShareLinkVO> getPopularShareLinks(Integer limit, Integer days);

    /**
     * 获取分享类型文本
     *
     * @param shareType 分享类型
     * @return 类型文本
     */
    String getShareTypeText(Integer shareType);

    /**
     * 获取分享状态文本
     *
     * @param status 状态值
     * @return 状态文本
     */
    String getShareStatusText(Integer status);

    /**
     * 转换为VO对象
     *
     * @param shareLink 分享链接实体
     * @return VO对象
     */
    ShareLinkVO convertToVO(ShareLink shareLink);

    /**
     * 批量转换为VO对象
     *
     * @param shareLinks 分享链接实体列表
     * @return VO对象列表
     */
    List<ShareLinkVO> convertToVOList(List<ShareLink> shareLinks);
}
